…example + HARVESTING.md

- ingest.rs: zero-dep, schema-flexible (column-alias) quote-aware CSV loader
  from_pypsa_csv(buses, lines, country) → PypsaImport. b=1/x (estimated from
  length+circuits at 0.33 Ω/km when absent), limit=s_nom (estimated by voltage
  class when absent); reports n_estimated_* for honest disclosure. ISO-2 country
  filter. PypsaImport::largest_component() (DFS) to drop the fragmentation that
  a country filter induces (cross-border ties + OSM gaps → λ₂≈0).
- examples/iberian.rs: loads the Zenodo 13358976 (ODbL) network, restricts to the
  connected core, synthesizes deterministic balanced injections, self-calibrates
  limits, trips the most-loaded line, prints spectral + cascade + geo epicentre.
  Graceful no-args usage (prints download recipe, exits 0).
- HARVESTING.md: process for any source/country — PyPSA-Eur/OSM (verified v0.3
  schema, metres/kV + fragmentation gotchas), Overpass/GridKit alternatives,
  ENTSO-E/ESIOS/Electricity-Maps live state, the column-alias contract,
  parameter derivation + honesty, and the predicted-vs-observed ICC/Jirak loop.

Validated end-to-end on real ES data: 705→261-bus connected core, one trip
cascades to 71/348 lines (20.4%), 21% connectivity loss, 43 islands; epicentre
clusters in northern Spain. 18 tests pass (4 ingest + 1 LCC new); clippy
-D warnings clean, fmt clean.

…tive resistance + Go-meta) + METHODS.md

basin.rs — the field half of the infight-vs-Raumgewinn duality, all four tools
as functions of the one Laplacian operator:
- kron_reduce: Schur complement L/L_II — basin→super-node, cross-border tiering;
  preserves effective resistance (Dörfler-Bullo), tested.
- effective_resistance + spectral_embedding: R_ij = (eᵢ−eⱼ)ᵀL⁺(eᵢ−eⱼ) metric and
  electrical coordinates — the CORRECT substrate for Morton/HHTL tiling (geography
  is not). Metric (triangle-inequality) tested.
- cheeger_sweep: normalized μ₂ + Fiedler sweep conductance with the Cheeger
  sandwich μ₂/2 ≤ h ≤ φ ≤ √(2μ₂) — the field↔cut exchange rate, both bounds tested.
- basin_lambda2 + Cauchy interlacing (tested) — per-tier field eigenvalue bounds
  the parent; HHTL hierarchy is spectrally consistent.
- infight_vs_raumgewinn → Regime{Infight,Raumgewinn,Balanced} (Go-meta); bridge
  cut classified Raumgewinn, tested.
- contingency_features → [Δλ₂, DK-rotation, Δφ, infight, raumgewinn]: the four
  methods' properties as per-contingency measurement variables.

METHODS.md — mathematical grounding connecting all four (one operator L; its L⁺,
spec, normalized spec, Schur complement), the anti-dilution table (combinatorial
λ₂ vs normalized μ₂; geography vs electrical distance; Weyl-equidistribution vs
Weyl-perturbation; reliability vs validity; IID vs Jirak), and the statistics
design: the four as a measurement battery → ICC/Pearson/Spearman/Cronbach with
mutual control variables via partial correlation r(x,y|z), convergent/discriminant
validity, and Jirak n^(p/2−1) significance (not IID Berry-Esseen).

26 tests pass; clippy -D warnings clean; fmt clean.

…field-tier synergy) + METHODS §6-8

sketch.rs (PROTOTYPE) — the fast-sketch synergy:
- resistance_sketch: Spielman-Srivastava effective resistance from k random ±1
  sign-projections (= vsa_bundle of sign fingerprints); R≈‖z_u−z_v‖², exact in
  expectation (MᵀM=L), JL-concentrated. Tested <12% rel-err at k=6000.
- walsh_pyramid_energy + fwht: Walsh/Morton pyramid coarse(Raumgewinn)↔fine
  (infight) collapse screen, O(N log N). Tested smooth=coarse, spike=fine,
  fwht∘fwht=N·I.
- Honest: dense L⁺ (accuracy demo, not the speed win — needs a fast solver);
  Walsh=eigenbasis only on hypercubes (a screen, eigensolve certifies); Jirak
  error bars.

splat.rs (PROTOTYPE) — the Gaussian-splat magnitude side:
- splat_neighborhood: SPD Σ fit to a bus's electrical neighbourhood (spectral
  embedding, resistance-weighted); anisotropy ≈ cut normal. Splats in electrical
  coords, NOT geography. Tested symmetric+PSD.
- ewa_coarsen vs box_coarsen + morton2: EWA anisotropic-Gaussian pyramid coarsen
  anti-aliases the Morton Z-jump seam. Tested wide-σ→box, tight-σ suppresses a
  seam outlier (box≈34→EWA≈1), morton2 known codes.
- Together §6+§7 = the OGAR bipolar-phase pyramid (sign=Walsh/XOR × magnitude=
  EWA/bundle), two-algebra rule respected.

METHODS.md §6/§7 document both; §8 frames the physical-fidelity ladder as
ITERATIONS on one extensible L-operator design (cheap→medium→fork adds columns +
swaps solver, never rewrites the field tier), not a limiting DC-vs-AC fork.
Anti-dilution table + README module map updated.

33 tests pass; clippy -D warnings clean; fmt clean.

…ing hypotheses (METHODS §9)

Runs on today's topology-only data; computes only what the data supports;
models missing per-asset variables as UNIFORM CONSTANTS (never noise — a
constant injects no spurious heterogeneity, so relative shape + ranking stay
clean).

- DataLevel / Capability / assess_capability: which outputs are valid
  (relative shape always; absolute MW / loss gradient / tech-debt differential
  gated on data presence).
- scale_susceptance + invariance test: uniform b-scale leaves flows, cascade,
  connectivity_loss EXACTLY invariant (λ₂→c·λ₂ cancels) — the math license for
  "assume Spain uniformly outdated" as a free relative-analysis null.
- with_uniform_derate: the global stress knob (not invariant; sweep + disclose).
- AgeModel: Uniform (null) vs DensityProxy (the Gegenhypothese — sparse/
  low-degree rural areas older, derived from topology ALONE, genuine
  heterogeneity) vs ModernizationSpend (per-bus newness from official Spanish
  grid-planning data). edge_age_factors + apply_aging (age→thermal derate).
- The three AgeModels are competing hypotheses, validated against the observed
  Spain-outage footprint via the §5 ICC/Pearson/Spearman battery (Jirak-sig) —
  turning the aging assumption into a falsifiable claim.

METHODS §9 documents it + cites the official data sources (planificacionelectrica
.es 2021-26/2025-30 plan ~260 projects PDF; MITECO portals; REE ISE_2024).
Anti-dilution rows + README updated.

38 tests pass; clippy -D warnings clean; fmt clean.

…layer

Consolidates every external source into one ledger (anti-dilution), organized
by the layer it feeds: (1) topology+params (PyPSA-Eur/OSM, GridKit, Overpass),
(2) live state (ENTSO-E/ESIOS/Electricity-Maps), (3) modernization/spend (Spanish
planificacionelectrica.es 2021-26/2025-30, MITECO portals, REE ISE_2024),
(4) renewable+storage context (Climate17, NECP 22.5 GW storage). Each row states
format/openness/extraction reality so no layer over-claims data it cannot read.

Flags the genuine new modeling axis the storage sources imply: storage = a
controllable injection (Pearl rung-2 do(p_i += discharge)) → a future
intervention.rs quantifying storage as collapse-prevention, slotting onto the
existing cascade with no field-tier change.

…s-overload validation caveat

DATA_SOURCES §5 (ground truth) + Awesome-Electrical-Grid-Mapping meta-source:
- ENTSO-E expert-panel final report (2026-03-20): the 28 Apr 2025 Iberian
  blackout was a VOLTAGE-COLLAPSE event — overvoltage-driven cascading
  generation disconnection + oscillations + reactive/voltage-control gaps — NOT
  a line-overload cascade.
- Eurosurveillance 30/26 + PMC12231376: human footprint — 147 excess deaths
  over 3 days (+4.2%; 65-84yo +7.9%), MoMo surveillance (severity target).

Critical honesty caveat (DATA_SOURCES §5 + METHODS anti-dilution rows): the DC
overload cascade does NOT reproduce the Iberian sequence; the voltage trigger
needs the AC fork (METHODS §8). What transfers is the mechanism-agnostic
STRUCTURAL field tier (Weyl/Cheeger/Fiedler/Kron) as a vulnerability screen, and
the Go-meta Raumgewinn lens for a system-wide event. Human footprint validates
severity (any mechanism) via the §5 ICC battery; ties to the public-health
surface. Guards against over-claiming "we model the Iberian blackout".

… 2024 — the empirical condition layer

REE Auditoria Calidad de Servicio RdT 2024 (availability, ENS, interruption
indices per element/region) is the measured condition/reliability data that
lifts the tech-debt modifier from the topology DensityProxy to real per-region
condition (DataLevel::WithHeterogeneousAssets): low availability / high ENS =
older/weaker asset = newness down. PDF → per-region condition index → newness
vector for AgeModel::ModernizationSpend.

…tion, 11 Apr 2025)

i-DE (Iberdrola DSO) capacity map = the distribution-layer complement to the
REE/PyPSA transmission layer: per-substation (Umspannwerk) available connection
capacity. Saturated substations (~0 headroom) = candidate stressed nodes feeding
AgeModel; dated 17 days pre-blackout = a near-contemporaneous as-of snapshot.
Map-style PDF → OCR/parse to a substation→capacity table.

…the ENTSO-E full report

Harvested the 50 MB ENTSO-E final report PDF (text-extracted) into a concrete,
numbers-quoted validation target in DATA_SOURCES §5:
- pre-conditions: ~5 GW exports; damped 0.63 Hz local + 0.2 Hz inter-area
  oscillations.
- 12:32:00 voltages rise; 12:33:16-18 overvoltage-protection cascade (~525/727/
  928/355 MW chunks); 12:33:20.473 Morocco AC trip; 12:33:21.535 France-Spain AC
  disconnect (the cut isolating Iberia); 12:33:23.960 HVDC trip → full
  separation; frequency → ~48 Hz.

Mechanism→model split made explicit: the TRIGGER (overvoltage gen trips, ~24 s)
is AC/reactive → AC fork only; the SEPARATION (FR-ES AC+HVDC disconnect) IS a
connectivity cut → the field tier (Cheeger min-cut / Fiedler λ₂ / Kron) does
model the separation geometry. Field tier = structural screen + separation;
AC fork = the voltage trigger. Sharpens the anti-over-claim caveat with receipts.

acflow.rs (the fork rung) — polar Newton-Raphson AC power flow on the full
π-model (R+jX+jB/2): AcSystem/AcBus/AcLine, ybus (complex), solve() with a
convergence flag (divergence = voltage-collapse signal), collapse_margin (the
loading nose). New types; DC field tier untouched (METHODS §8 iterations-not-
fork). This is the rung that models the voltage mechanism the Iberian blackout
actually exhibited. Tests: flat no-load, self-consistent NR balance, Ybus
symmetry, heavy-load divergence, finite collapse margin. PROTOTYPE (no PV/PQ
Q-limit switching, no taps).

stats.rs — zero-dep reliability/validity (Pearson, tie-aware Spearman, Cronbach
α, ICC(2,1), zscore), mirroring ndarray::hpc::reliability. Tests incl. the
ICC-catches-bias-Pearson-misses signature.

examples/validate.rs — computes modifiers from the data we have (topology
DensityProxy / Gegenhypothese), applies aging, sweeps a fixed contingency set
across time slices, extracts the 4 field factors per contingency, runs the
battery (Cronbach α + ICC + pairwise Spearman) + time test-retest. On the 5x5
synthetic: d_lambda2 ≡ raumgewinn (both λ₂-derived), negative α confirms the
factors are DISTINCT facets (infight vs Raumgewinn), not one scale — exactly the
discriminant-validity result expected.

48 tests pass; clippy -D warnings clean; fmt clean.

… committed)

Created GitHub Release perturbation-sim-data-v0.1 on AdaWorldAPI/lance-graph with
buses.csv + lines.csv (PyPSA-Eur/OSM, ODbL, © OSM contributors) attached as
assets — so clones never auto-pull the data and the repo stays lean. Official
Spanish PDFs remain links-only (not re-hosted, licensing). DATA_SOURCES.md +
HARVESTING.md updated with the release mirror curl recipe and a no-data-in-git
note.

…amid) + helix-360/turbovec live-encoding doctrine

- ndarray-simd feature (optional, off by default → crate stays zero-dep): the
  Morton/Walsh pyramid transform (sketch::walsh_pyramid_energy) routes through
  ndarray::simd::wht_f32 (AVX-512/AMX, x86-64-v4) when enabled; scalar fwht
  fallback otherwise. ndarray = AdaWorldAPI fork (path dep; git alternative
  documented). Verified: 48 tests + clippy clean under BOTH default and
  `--features ndarray-simd` (target-cpu=native); the fork compiles in ~20s.
- METHODS §10: documents the wiring + the deeper tile-specific ndarray targets
  (simd_soa::MultiLaneColumn, hpc::codec::ctu HEVC-quadtree, hilbert, U8x64/
  hamming). And the live-4-factor-encoding doctrine: the factors are unit-free
  spectral magnitudes → carry them on the GENERIC helix Signed360 residue tenant
  (6B/factor, L1-metric-safe so Spearman/ICC survive the encoding), NOT an
  electricity-specific tenant; turbovec ANN for episodic factor-vector search;
  electricity-specific encoding reserved for the raw |V|/MW layer; compute stays
  on raw f64. Anti-dilution rows + README updated.

Real-Iberian validate (261-bus core, release build): Cronbach α=-0.83 (factors
are distinct facets, not one scale), spectral cluster convergent (ρ 0.96-1.00),
infight orthogonal to it (ρ≈±0.05 — discriminant validity = the Go duality
measured), time test-retest ρ≈0.90 (basin ranking stable). Basin model verified.

…mpts, canonical caption

Reproducible spec for the perturbation-shape figure: the canonical caption with
the measured numbers, the non-negotiable rigor points (λ₂≠μ₂, factor symbols,
the DC-screen honesty disclaimer, illustrative-topology label), and two prompts
(journal-figure for the math/stats audience; dark pitch variant for talks).
Travels with the crate; final PNGs go under docs/.

…theorem mapping

Adds the second figure spec: the stacked 2-bit×2-bit (4×4) Morton/z-order pyramid
for spatial perturbation, with each theorem mapped to its pyramid structure —
Weyl/Δλ₂ at the coarse top, Davis-Kahan/sinθ_DK at the reorienting partition,
Cheeger/Δφ on the inter-tile seam (the exchange rate), infight at the fine
bottom, Kron on the 4→1 coarsen arrow. Two algebras labelled (Walsh/XOR sign axis,
EWA-splat magnitude axis); the bipolar-phase = Walsh-Hadamard identity; and the
geography-trap + screen-not-exact + SIMD-WHT honesty strip.

P2-1 (Cargo.toml): the optional ndarray dep was a PATH dep — Cargo reads the
path manifest at resolution, so a clean checkout without ../../../ndarray failed
even with ndarray-simd OFF, breaking the zero-dep default. Switched to the GIT
source (helix pattern): it resolves remotely and is only fetched/built when the
feature activates it. Verified: default `cargo test` now resolves the git dep
without any local sibling — 49 tests pass.

P2-2 (cascade.rs): edge_field recorded the all-lines BASE flow for lines that
trip in later rounds, underreporting redistribution-driven trips (a line with
~0 base flow that trips on a large redistributed flow showed ~0 footprint). Now
capture trip_flow[e] = the current-round flow at the round each line trips
(seed/survivors default to base); edge_field for a tripped line uses that
overload. New regression test round_trip_edge_field_is_the_overload_not_base
asserts a round-≥1 trip's edge_field exceeds its limit.

49 tests pass; clippy -D warnings clean; fmt clean.

… + Cheeger boundary

examples/weakest_links.rs: on a grid (real PyPSA core via args, else synthetic),
reports (1) STRUCTURAL weakest links — per-line single-trip λ₂-loss (Weyl/Fiedler,
limit-independent; flags bridges whose trip alone disconnects the core), (2) the
CHEEGER local boundary — the min-conductance sweep cut (μ₂, φ, which buses on the
small side, which lines cross the seam = the 'flap'), (3) OPERATIONAL weakest
links — per-line N-1 cascade size under self-calibrated limits. Clippy-clean.

The ndarray-simd Walsh-Hadamard path uses AVX-512 under x86-64-v4 — NOT AMX.
AMX is int8/bf16 tile-GEMM (ndarray::hpc::amx_matmul); this crate's WHT is f32
and its field tier f64, neither of which maps to AMX tiles. Corrected the loose
'AVX-512/AMX' wording in Cargo.toml/README/METHODS §10; noted the int8 AMX path
(matmul_i8_to_i32) as a possible-but-unwired future option.

… + AMX two-sided note

weakest_links example: replaced the O(m) full-eigensolve structural sweep with
first-order Fiedler sensitivity ∂λ₂/∂wₑ = (v₂[a]−v₂[b])²·bₑ — one eigensolve
ranks all m lines, exact λ₂-loss recomputed only for the top 10 (bridge flag);
operational cascade bounded to the top-25 candidates (max_rounds 16). The full
N-1 cascade sweep was intractable (timeout).

METHODS §10: corrected the AMX note to the two-sided picture — sign side
(Walsh/XOR WHT) = AVX-512 f32, wired here; magnitude side (EWA-splat / Morton
tile) = AMX bf16/int8 tile-GEMM in ndarray (bf16_tile_gemm/amx_matmul/edge_codec),
genuinely AMX-backed but not yet wired in this crate.

…ation

Susceptances are ~6e-5 (estimated from line length in metres), so the Fiedler
sensitivities are ~1e-8 and printed as 0.00000 in fixed notation — misleading.
Switched to {:.3e}; the ranking (line 150 top, sens 2.07e-8 / λ₂-loss 39%) and
base λ₂ = 3.15e-7 (the OSM ES core is very weakly connected) now read correctly.

… PAPER §4.3

examples/hhtl_levels.rs: recursive spectral (Cheeger/Fiedler) bisection builds
the HHTL tree (HEEL→HIP→TWIG→LEAF); at each tier computes Weyl (per-basin λ₂),
Davis-Kahan (gap λ₃−λ₂), Cheeger (μ₂/φ), and Kron (super-graph: #basins +
out-of-family ties). On the real ES core the readings cohere: λ₂ rises monotone
HEEL→LEAF (Cauchy interlacing), and the HIP tier has exactly 2 out-of-family ties
= lines 46 & 150 = the weakest links the other analyses found. PAPER §4.3
records the table + the OGAR mapping (a 2nd inter-basin corridor = a 3rd
out-of-family EdgeBlock slot, λ₂ gain bounded by interlacing).

… (Braess) finding

examples/reinforce.rs: adds the optimal 3rd corridor across the Cheeger seam
(Fiedler-extreme pair, max ∂λ₂/∂w; an OGAR 3rd out-of-family EdgeBlock edge),
measures exact Δλ₂ and the seam-line cascade before/after.

Headline scientific finding (ES core, buses 1199–4258): the corridor raises λ₂
by +136% AND lowers connectivity-loss (39.0%→34.4%) — yet the cascade WORSENS
(48→95 trips). One intervention moves the two axes in OPPOSITE directions:
Raumgewinn improves, infight worsens — the measured infight⊥Raumgewinn
orthogonality (ρ≈0.05) realized in a single experiment, a power-grid Braess
paradox. Constructive solution (PAPER §4.4): match the remedy to the failure
axis — a corridor (λ₂/Cheeger/Kron) fixes separation/islanding; an overload
cascade needs limit re-rating/redispatch, and structural reinforcement must be
co-designed with limit upgrades or it backfires. The Go-meta Regime classifier
says which axis a contingency loads. Bilingual EN/DE.

… HHTL residents (§4.5/§4.6)

- timing.rs: the cascade clock. rounds=hops; inertia sets time-per-hop via the
  swing equation RoCoF=f₀·ΔP/2H (rocof_hz_per_s, per_hop_time). cascade_wall_time
  / implied_dt_per_hop; mechanism_from_timescale (the 27 s = electromechanical
  tell). HHTL_WEIGHTS (4:1→1:4 HEEL→LEAF) + tier_composite (per-tier R/I blend).
  collapse_number Π = (raumgewinn·spread)/(infight·inertia) = (time·distance)/
  (...) — proposed scaling law [H], inverse correlation. 53 tests.
- examples/hhtl_resident.rs: HH=Raumgewinn(λ₂) vs TL=infight per basin →
  measured on ES leaf basins: Pearson +0.53, Spearman +0.44, ICC +0.55
  (POSITIVELY coupled) — vs global ρ≈0.05 (orthogonal). The orthogonality is
  SCALE-DEPENDENT → motivates per-tier weighting.
- PAPER §4.5 (scale-dependent coupling) + §4.6 (time mediator, inertia clock,
  27 s tell, per-tier weights, the Π collapse-number law). Bilingual EN/DE.

clippy -D warnings clean; fmt clean.